SDK接入指南
一、原生平台
1.1 iOS
1.1.1 工程配置
| ①添加framework文件 |
②设置framework搜索路径 |
③设置header搜索路径 |
 |
 即存放netshield.framework的本地目录 |
即netshield.framework的全路径追加"/Headers" |
1.1.2 接口说明
头文件:LibNetshield.h
| 方法 |
说明 |
+ (void)startService:key:completionHandler: |
启动防护服务
pid-项目ID
key-授权密钥
completionHandler-启动回调函数,详见示例代码 |
+ (int)getLocalhostPort: |
根据规则名获取本地端口 |
+ (void)stopService |
停止防护服务,释放资源 |
1.1.3 示例代码
// 引入头文件
#import <LibNetshield.h>
// 启动防护服务
[LibNetshield startService:@"123"
key:@"12345678901234567890"
completionHandler:^(BOOL success, NSString *errMsg, NSString *clientIP) {
// startResult SDK是否成功启动 YES-启动成功 NO-启动失败
// errMessage 启动失败时用于获取失败原因,启动成功时可忽略
// clientIP 启动成功时为客户端真实IP,启动失败为空
if (startResult) {
NSLog(@"SDK started success,clientIP:%@", clientIP);
} else {
NSLog(@"SDK started failed");
}
}];
// 根据规则名获取本地端口
int localPort = [LibNetshield getLocalhostPort:@"test;10001"];
// 通过本地端口访问真实后端服务
NSString *url = [NSString stringWithFormat:@"http://127.0.0.1:%d", localPort];
// 停止防护服务,释放资源
[LibNetshield stopService];
#import <LibNetshield.h>
[LibNetshield startService:@"123"
key:@"12345678901234567890"
completionHandler:^(BOOL success, NSString *errMsg, NSString *clientIP) {
if (startResult) {
NSLog(@"SDK started success,clientIP:%@", clientIP);
} else {
NSLog(@"SDK started failed");
}
}];
int localPort = [LibNetshield getLocalhostPort:@"test;10001"];
NSString *url = [NSString stringWithFormat:@"http://127.0.0.1:%d", localPort];
[LibNetshield stopService];
1.2 macOS平台
1.2.1 工程配置
| ①添加dylib文件 |
②设置dylib链接搜索路径 |
 |
 即存放libnetshield.dylib的本地目录 |
1.2.2 接口说明
| 方法 |
说明 |
void startNetshieldService(const char *pid, const char *key, void (*completionHandler)(int, const char *, const char *)) |
启动防护服务
pid-项目ID
key-授权密钥
completionHandler-启动回调函数,详见示例代码 |
int getLocalhostPort(const char *) |
根据规则名获取本地端口 |
void stopNetshieldService() |
停止防护服务,释放资源 |
1.2.3 示例代码
以下代码为c++和objc混编,需要将接入源码的 .m 后缀修改为 .mm
①添加extern函数声明
#ifdef __cplusplus
extern "C" {
#endif
extern void startNetshieldService(const char *, const char *, void (*)(int, const char *, const char *));
extern int getLocalhostPort(const char *);
extern void stopNetshieldService();
#ifdef __cplusplus
}
#endif#ifdef __cplusplus
extern "C" {
#endif
extern void startNetshieldService(const char *, const char *, void (*)(int, const char *, const char *));
extern int getLocalhostPort(const char *);
extern void stopNetshieldService();
#ifdef __cplusplus
}
#endif
②调用接口
// 启动防护服务
NSString *pid = @"123";
NSString *key = @"12345678901234567890";
startNetshieldService([pid UTF8String], [key UTF8String], [](int startResult, const char *errMessage, const char *clientIP){
// startResult SDK是否成功启动 0-启动成功 -1-启动失败
// errMessage 启动失败时用于获取失败原因,启动成功时可忽略
// clientIP 启动成功时为客户端真实IP,启动失败为空
if (0 == startResult) {
NSLog(@"SDK started success,clientIP:%s", clientIP);
} else {
NSLog(@"SDK started failed,err:%s", errMessage);
}
});
// 根据规则名获取本地端口
int localhostPort = getLocalhostPort("240.0.0.2;80");
// 通过本地端口访问真实后端服务
NSString *localhostUrl = [NSString stringWithFormat:@"http://127.0.0.1:%d", localhostPort];
// 停止防护服务,释放资源
stopNetshieldService();
NSString *pid = @"123";
NSString *key = @"12345678901234567890";
startNetshieldService([pid UTF8String], [key UTF8String], [](int startResult, const char *errMessage, const char *clientIP){
if (0 == startResult) {
NSLog(@"SDK started success,clientIP:%s", clientIP);
} else {
NSLog(@"SDK started failed,err:%s", errMessage);
}
});
int localhostPort = getLocalhostPort("240.0.0.2;80");
NSString *localhostUrl = [NSString stringWithFormat:@"http://127.0.0.1:%d", localhostPort];
stopNetshieldService();
1.3 Android平台
1.3.1 工程配置
| ①app/build.gradle添加aar路径 |
②调整minSdkVersion为21或以上 |
dir中的目录即即存放netshield.aar的本地目录,可以为全路径 |
 |
1.3.2 接口说明
类文件:com.netshield.Netshield
| 方法 |
说明 |
static int startService(String pid, String key) |
启动防护服务
pid-项目ID
key-授权密钥 |
static String getClientIP() |
获取客户端真实IP,需要在SDK启动成功后调用 |
static int getLocalhostPort(String rule) |
根据规则名获取本地端口 |
static void stopService() |
停止防护服务,释放资源 |
1.3.2 示例代码
// 启动防护服务
int code = Netshield.startService("123", "12345678901234567890");
if (code == 0) {
// 获取真实的客户端IP
String clientIP = Netshield.getClientIP();
Log.d("SDK", "Client IP: " + clientIP);
} else {
Log.e("SDK", "SDK初始化失败");
}
// 根据规则名获取本地端口
int localPort = Netshield.getLocalhostPort("test;10001");
// 通过本地端口访问真实后端服务
String url = String.format("http://127.0.0.1:%d", localPort);
// 停止防护服务,释放资源
stopService();
int code = Netshield.startService("123", "12345678901234567890");
if (code == 0) {
String clientIP = Netshield.getClientIP();
Log.d("SDK", "Client IP: " + clientIP);
} else {
Log.e("SDK", "SDK初始化失败");
}
int localPort = Netshield.getLocalhostPort("test;10001");
String url = String.format("http://127.0.0.1:%d", localPort);
stopService();
1.4 Windows平台
1.4.1 工程配置
将netshield.dll放置到exe同级目录
1.4.2 接口说明
| 方法 |
说明 |
int startNetshieldService(const char *pid, const char *key) |
启动防护服务
pid-项目ID
key-授权密钥 |
const char *getClientIP() |
获取客户端真实IP,需要在SDK启动成功后调用 |
int getLocalhostPort(const char *rule) |
根据规则名获取本地端口 |
void stopNetshieldService() |
停止防护服务,释放资源 |
1.4.3 示例代码
① 动态加载DLL
HMODULE netshieldDll = LoadLibrary(L"netshield.dll");
auto (*startNetshieldService)(const char *, const char *) = reinterpret_cast<int(__cdecl *)(const char *, const char *)>(GetProcAddress(netshieldDll, "startNetshieldService"));
auto (*getClientIP)() = reinterpret_cast<const char *(__cdecl *)()>(GetProcAddress(netshieldDll, "getClientIP"));
auto (*getLocalhostPort)(const char *) = reinterpret_cast<int(__cdecl *)(const char *)>(GetProcAddress(netshieldDll, "getLocalhostPort"));
auto (*stopNetshieldService)() = reinterpret_cast<void(__cdecl *)()>(GetProcAddress(netshieldDll, "stopNetshieldService"));
HMODULE netshieldDll = LoadLibrary(L"netshield.dll");
auto (*startNetshieldService)(const char *, const char *) = reinterpret_cast<int(__cdecl *)(const char *, const char *)>(GetProcAddress(netshieldDll, "startNetshieldService"));
auto (*getClientIP)() = reinterpret_cast<const char *(__cdecl *)()>(GetProcAddress(netshieldDll, "getClientIP"));
auto (*getLocalhostPort)(const char *) = reinterpret_cast<int(__cdecl *)(const char *)>(GetProcAddress(netshieldDll, "getLocalhostPort"));
auto (*stopNetshieldService)() = reinterpret_cast<void(__cdecl *)()>(GetProcAddress(netshieldDll, "stopNetshieldService"));
② 调用接口
// 启动防护服务
int rc = startNetshieldService("123", "12345678901234567890");
if (rc == 0) {
// 获取真实的客户端IP
const char* clientIP = getClientIP();
printf("Client IP: %s\n", clientIP);
} else {
printf("SDK初始化失败\n");
}
// 根据规则名获取本地端口
int localPort = getLocalhostPort("test;10001");
// 通过本地端口访问真实后端服务
char url[1024];
snprintf(url, sizeof(url), "http://127.0.0.1:%d", localPort);
// 停止防护服务,释放资源
// 如果遇到进程无法退出,需要在main函数结束前调用该函数
stopNetshieldService();
int rc = startNetshieldService("123", "12345678901234567890");
if (rc == 0) {
const char* clientIP = getClientIP();
printf("Client IP: %s\n", clientIP);
} else {
printf("SDK初始化失败\n");
}
int localPort = getLocalhostPort("test;10001");
char url[1024];
snprintf(url, sizeof(url), "http://127.0.0.1:%d", localPort);
stopNetshieldService();
二、Unity平台
1、按下图目录结构拷贝SDK文件
├── Assets
│ ├── Plugins
│ │ ├── Netshield
│ │ │ ├── Android
│ │ │ │ ├── netshield-release.aar
│ │ │ ├── Windows
│ │ │ │ ├── netshield.dll
│ │ │ ├── iOS
│ │ │ │ ├── netshield.framework
│ │ │ ├── macOS
│ │ │ │ ├── libnetshield.dylib
│ └── Scripts
│ ├── Netshield
│ │ ├── INetshieldInterface.cs
│ │ ├── Netshield.cs
│ │ ├── impl
│ │ │ ├── Netshield4Android.cs
│ │ │ ├── Netshield4OSX.cs
│ │ │ ├── Netshield4Others.cs
│ │ │ ├── Netshield4Windows.cs
Netshield.zip
2、接口说明
| 方法 |
说明 |
Netshield4Unity.GetInstance() |
获取Netshield4Unity单例对象 |
void StartService(string pid, string key, CompletionHandler completionHandler) |
启动防护服务
pid-项目ID
key-授权密钥
completionHandler-启动回调函数,详见示例代码 |
void StopService() |
停止防护服务,释放资源 |
int GetLocalhostPort(string rule) |
根据规则名获取本地端口 |
3、示例代码
// 启动防护服务
Netshield4Unity.GetInstance().StartService("123", "12345678901234567890", (result, msg, ip) => {
// result SDK是否成功启动 0-启动成功 -1-启动失败
// msg 启动失败时用于获取失败原因,启动成功时可忽略
// ip 启动成功时为客户端真实IP,启动失败为空
Debug.Log(result == 0 ? $"Success: {ip}" : $"Error: {msg}");
});
// 根据规则名获取本地端口
int localPort = Netshield.Netshield4Unity.GetInstance().GetLocalhostPort("test;10001");
// 通过本地端口访问真实后端服务
var url = "http://127.0.0.1:" + localPort;
// 停止防护
Netshield4Unity.GetInstance().StopService();
Netshield4Unity.GetInstance().StartService("123", "12345678901234567890", (result, msg, ip) => {
Debug.Log(result == 0 ? $"Success: {ip}" : $"Error: {msg}");
});
int localPort = Netshield.Netshield4Unity.GetInstance().GetLocalhostPort("test;10001");
var url = "http://127.0.0.1:" + localPort;
Netshield4Unity.GetInstance().StopService();
三、Cocos Creator
3.1 拷贝js接口文件到脚本目录
Netshield.js
3.2 拷贝库文件到各平台
3.2.1 iOS和mac
| ①将SDK添加到工程中 |
②选择同时添加到iOS和macOS中 |
 |
 |
| ③将桥接文件添加到Classes目录 |
④检查结果 |
 |
 |
| ⑤iOS-添加framework文件 |
⑥iOS-设置framework搜索路径 |
 |
 ${SRCROOT}/../../../../../netshield/ios_mac/ios |
| ⑦mac-添加dylib文件 |
⑧mac-设置dylib链接搜索路径 |
 |
 ${SRCROOT}/../../../../../netshield/ios_mac/mac |
| ⑨mac-设置dylib运行搜索路径 |
|
 @executable_path/../Frameworks |
|
3.2.2 Android
| ①app/build.gradle添加aar路径 |
②调整minSdkVersion为21或以上 |
implementation fileTree(dir: '../../../../../../netshield/android', include: ['*.aar'] |
 |
3.2.3 Windows
| ①将代码文件添加到工程中 |
②在jsb_module_register.cpp中注册 |
 |
 |
| 步骤②代码 |
③将dll文件添加到工程中 |
#if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32) #include "NetshieldBridge.hpp" #endif
// 以下代码需要添加到jsb_register_all_modules函数中 #if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32) se->addRegisterCallback(register_netshield_bridge); #endif |
 |
3.3 调用接口
async onStartSDK() {
// 启动防护服务
console.log("启动SDK...");
try {
const result = await Netshield.start("123", "1231231231231231231231");
if (result.startResult === 0) {
// result.clientIP为真实的客户端IP
console.log("SDK 启动成功,IP:" + result.clientIP);
} else {
console.log("SDK 启动失败:" + result.errorMessage);
}
} catch (error) {
console.log("SDK 启动异常:" + error);
}
},
onRequestPage() {
// 根据规则名获取本地端口
const localhostPort = Netshield.getLocalhostPort("240.0.0.2;80");
// 通过本地端口访问真实后端服务
let url = "http://127.0.0.1:" + this.localhostPort;
console.log("访问页面: " + url);
}
onStopSDK() {
console.log("停止SDK");
Netshield.stop();
console.log("SDK 已停止");
},async onStartSDK() {
console.log("启动SDK...");
try {
const result = await Netshield.start("123", "1231231231231231231231");
if (result.startResult === 0) {
console.log("SDK 启动成功,IP:" + result.clientIP);
} else {
console.log("SDK 启动失败:" + result.errorMessage);
}
} catch (error) {
console.log("SDK 启动异常:" + error);
}
},
onRequestPage() {
const localhostPort = Netshield.getLocalhostPort("240.0.0.2;80");
let url = "http://127.0.0.1:" + this.localhostPort;
console.log("访问页面: " + url);
}
onStopSDK() {
console.log("停止SDK");
Netshield.stop();
console.log("SDK 已停止");
},
四、Flutter
SDK以flutter plugin的形式提供
4.1 添加依赖
通过本地路径的方式引入plugin
dependencies:
netshield4flutter:
path: ../path/to/your/netshield4flutterdependencies:
netshield4flutter:
path: ../path/to/your/netshield4flutter
4.2 接入代码(详细用法请参考plugin example)
import 'package:netshield4flutter/netshield4flutter.dart';
final _netshield4flutterPlugin = Netshield4flutter();
try {
// 启动防护服务
final startResult = await _netshield4flutterPlugin.startService('123', '12345678901234567890');
if (startResult.isSuccess) {
print("SDK 已启动");
// startResult.clientIP为真实的客户端IP
print("Client IP: ${startResult.clientIP}");
} else {
print("SDK 启动失败: ${startResult.errorMessage}");
}
} on PlatformException {
print("SDK 启动失败");
}
int localhostPort = -1;
try {
// 根据规则名获取本地端口
localhostPort = await _netshield4flutterPlugin.getLocalhostPort("240.0.0.2;80");
// 通过本地端口访问真实后端服务
String url = "http://127.0.0.1:$localhostPort";
} on PlatformException {
print("无法获取本地端口");
}
// 可选代码,应用退出时可自动关闭
try {
// 关闭防护服务
await _netshield4flutterPlugin.stopService();
print("SDK 已停止");
} on PlatformException {
print("SDK 停止失败");
}import 'package:netshield4flutter/netshield4flutter.dart';
final _netshield4flutterPlugin = Netshield4flutter();
try {
final startResult = await _netshield4flutterPlugin.startService('123', '12345678901234567890');
if (startResult.isSuccess) {
print("SDK 已启动");
print("Client IP: ${startResult.clientIP}");
} else {
print("SDK 启动失败: ${startResult.errorMessage}");
}
} on PlatformException {
print("SDK 启动失败");
}
int localhostPort = -1;
try {
localhostPort = await _netshield4flutterPlugin.getLocalhostPort("240.0.0.2;80");
String url = "http://127.0.0.1:$localhostPort";
} on PlatformException {
print("无法获取本地端口");
}
try {
await _netshield4flutterPlugin.stopService();
print("SDK 已停止");
} on PlatformException {
print("SDK 停止失败");
}
五、UniApp
5.1 uts插件
5.1.1 放置插件
| 将uts插件放到uni_modules目录下 |
 |
5.1.2接入代码
import { startNetshieldService, stopNetshieldService, getLocalhostPort } from "@/uni_modules/dev-netshield";
export default {
methods: {
startSDK() {
console.log("启动SDK");
// 启动防护服务
startNetshieldService("123", "1231231231231231231231", (res : Array<string>) => {
if ("0" == res[0]) {
console.log("SDK启动成功");
// result[2]为真实的客户端IP
console.log("客户端真实IP:" + res[2]);
} else {
console.log("SDK启动失败");
console.log("错误信息:" + res[1]);
}
});
},
browse() {
// 根据规则名获取本地端口
const localhostPort = getLocalhostPort("240.0.0.2;80");
// 通过本地端口访问真实后端服务
let url = "http://127.0.0.1:" + localhostPort;
console.log("访问页面: " + url);
},
stopSDK() {
console.log("关闭SDK");
stopNetshieldService();
console.log("SDK已关闭");
}
}
}import { startNetshieldService, stopNetshieldService, getLocalhostPort } from "@/uni_modules/dev-netshield";
export default {
methods: {
startSDK() {
console.log("启动SDK");
// 启动防护服务
startNetshieldService("123", "1231231231231231231231", (res : Array<string>) => {
if ("0" == res[0]) {
console.log("SDK启动成功");
// result[2]为真实的客户端IP
console.log("客户端真实IP:" + res[2]);
} else {
console.log("SDK启动失败");
console.log("错误信息:" + res[1]);
}
});
},
browse() {
// 根据规则名获取本地端口
const localhostPort = getLocalhostPort("240.0.0.2;80");
// 通过本地端口访问真实后端服务
let url = "http://127.0.0.1:" + localhostPort;
console.log("访问页面: " + url);
},
stopSDK() {
console.log("关闭SDK");
stopNetshieldService();
console.log("SDK已关闭");
}
}
}
5.2 原生插件
5.2.1 放置及启用插件
①将native插件放到nativeplugins目录下![]() |
②在manifest.json中选择本地插件![]() |
 |
 |
5.2.2 接入代码
const netshieldNativePlugin = uni.requireNativePlugin('netshieldNativePlugin');
export default {
methods: {
startSDK() {
console.log("启动SDK");
// 启动防护服务
netshieldNativePlugin.startNetshieldService("123", "1231231231231231231231", (ret) => {
if ("0" == ret.startResult) {
console.log("SDK启动成功");
// ret.clientIP为真实的客户端IP
console.log("clientIP:" + ret.clientIP);
} else {
console.log("SDK启动失败");
console.log("errMessage:" + ret.errMessage);
}
});
},
browse() {
// 根据规则名获取本地端口
const localhostPort = netshieldNativePlugin.getLocalhostPort("240.0.0.2;80");
// 通过本地端口访问真实后端服务
let url = "http://127.0.0.1:" + localhostPort;
console.log("访问页面: " + url);
},
stopSDK() {
console.log("关闭SDK");
netshieldNativePlugin.stopNetshieldService();
console.log("SDK已关闭");
}
}
}const netshieldNativePlugin = uni.requireNativePlugin('netshieldNativePlugin');
export default {
methods: {
startSDK() {
console.log("启动SDK");
// 启动防护服务
netshieldNativePlugin.startNetshieldService("123", "1231231231231231231231", (ret) => {
if ("0" == ret.startResult) {
console.log("SDK启动成功");
// ret.clientIP为真实的客户端IP
console.log("clientIP:" + ret.clientIP);
} else {
console.log("SDK启动失败");
console.log("errMessage:" + ret.errMessage);
}
});
},
browse() {
// 根据规则名获取本地端口
const localhostPort = netshieldNativePlugin.getLocalhostPort("240.0.0.2;80");
// 通过本地端口访问真实后端服务
let url = "http://127.0.0.1:" + localhostPort;
console.log("访问页面: " + url);
},
stopSDK() {
console.log("关闭SDK");
netshieldNativePlugin.stopNetshieldService();
console.log("SDK已关闭");
}
}
}
六、注意事项
- 初始化时机:在应用启动后尽早调用初始化方法
- 错误处理:
- iOS/macOS通过
completionHandler回调判断结果
- 其他平台通过返回值判断(0=成功)
- 资源释放:退出时需调用
stopNetshieldService方法释放资源
- 动态库依赖:Windows需正确部署
netshield.dll,iOS和macOS平台的framework必须配置为Embed模式,否则会导致运行时崩溃
七、技术支持
商务合作与技术支持请联系telegram: youxidun